在開始打造 Agent 跟前後端之前，我想先把這個系統的輸入與輸出講得更具體一點。

Analysis 大家都很熟悉，所以這一篇可以把它當成一次對齊：確認我們對 Analysis 是什麼、input 是什麼，以及最後要產生什麼 output，有相同的認知。

今天會帶過以下幾件事：

1. 我們會使用什麼資料？
2. 一個 Analysis 到底長什麼樣子？
3. 系統的 input 是什麼？
4. 我們預期系統產生什麼 output？
5. 哪些內容需要被保存？
6. 要怎麼進一步 scale up？

Data

原則上，這個平台不應該被綁定在特定 datasource 或 file format 上。

資料可能來自：

• CSV
• XLSX
• PDF
• relational databases
• 其他 structured 或 semi-structured sources

不過在這個系列裡，我們主要使用 CSV。

這次會使用 Kaggle 上的資料集：Global YouTube Trends & Creator Stats (2017–2023)。

其中會使用這個 csv：

youtube_trending_cleaned_us.csv

可以先稍微看一下資料、熟悉它的結構，但這個系列不會花太多篇幅介紹 dataset 本身。

Analysis Examples

有了資料之後，下一個問題是：

到底什麼算是一個 Analysis？

簡單的 Analysis 可以是：

• 計算 average 或 total
• 找出 Top N records
• 對不同 category 進行 group 與 ranking
• 計算 distribution

也可以包含更多分析與推理：

• 找出一段時間內的趨勢
• 找出 unusual 或 abnormal patterns
• 分析兩個欄位之間的關係
• 比較不同群體的表現
• 找出某個變化可能的原因

以這次的資料集為例：

• 哪些 video categories 得到最多 views？
• Viewing activity 隨時間有什麼變化？
• Likes 和 views 之間有沒有關聯？
• 哪些 channels 經常出現在 trending videos 裡？
• 有沒有某些 videos 或 channels 的表現明顯和其他資料不同？

基本的視覺化如下：

What Is the Input?

如果我們先假設整個平台已經完成，那 Agent 真正收到的 input 是什麼？

除了資料本身之外，還包含：

Human Intent / Domain Knowledge

資料告訴 Agent 有什麼。

使用者則告訴 Agent 自己想看的方向，以及哪些事情是重要的。

Data Input

對 project 或 POC 來說，最簡單的方式就是讓使用者直接上傳檔案，再把檔案存在地端。

到了 production environment，structured data 通常會存在 database。

以 PostgreSQL 為例，它可以提供：

• Efficient querying — 只取出 Analysis 需要的資料。
• Performance — index 與 query optimization 可以加速 filtering、joins 與 aggregations。
• Concurrency and consistency — 多個 users 或 agents 可以同時安全地存取資料。
• Access control — 可以限制不同使用者或服務能存取的資料範圍。

對 Agent system 來說，重點在於很多分析其實不需要讀取整個 database。

只要產生正確的 query，就可以只取得當下真正需要的資料。

例如：

User Intent → Agent → SQL Query → PostgreSQL → Relevant Result

而不是：

Entire Database → Agent

這裡重要的 design principle 是：

Agent 不應該在意資料實際存放在哪裡，而是透過 datasource layer 來存取資料。

Human Input

在這個 project 裡，我們主要會使用文字作為 input，不會特別處理圖像或聲音。

就像使用 ChatGPT 一樣，使用者會透過 chat interface 和 Agent 互動。

例如：

User: 幫我找出 total views 最高的 Top 10 channels。

User: views 這個 column 裡有沒有異常值？

User: Viewing activity 隨時間的變化趨勢是什麼？有沒有什麼值得注意的 insight？

但 human input 不只是問題本身。

使用者也可以提供 Agent 無法單純從 dataset 中推導出的 domain knowledge 或額外規則。

例如：

User: 忽略來自 internal test channels 的 videos。

或是：

User: 比較 channels 時，只考慮至少有 10 支 trending videos 的 channels。

這些額外 context，都會成為 Agent 理解並執行 Analysis 的一部分。

What Is the Expected Output?

我會把 output 分成兩個部分：

1. Agent Response
2. Final Analysis Output

Agent Response

如果需求清楚，Agent 應該直接往下執行，而不是要求使用者確認每一個步驟。

可能包含：

• calling tools
• inspecting the datasource
• generating analysis code
• executing the code
• interpreting the execution result

例如：

User: 幫我找出 total views 最高的 Top 10 channels。

Agent: 我會先依 channel 彙總 views，進行排名，再回傳 Top 10。

如果是模糊的需求，Agent 則應該先詢問，而不是自己做假設或亂做決定。

例如：

User: 幫我找出表現最好的 channels。

Agent: 你希望用什麼方式定義「表現最好」？Total views、average views per video、engagement rate，還是其他 metric？

我們的目標不是完全把人從流程中移除，而是只讓人在真正重要的地方介入。

Final Output

Final Analysis output 需要用 frontend 可以呈現的格式輸出。

常見選擇包括 JSON、Markdown、chart specifications、HTML，或 CSV / PDF 等 generated files。

在這個 project 裡，我們主要使用 HTML report。

原因是因為它可以靈活組合：

• text
• tables
• charts
• highlighted findings
• interactive elements

而且更重要的是 HTML 可以是動態的。

Report structure 可以保持一致，但內容會根據每次的資料自動調整。

例如，一個 Analysis 可能永遠要求 highlight 表現最好的 category。

這時 report 不應該寫死某個 category name，而是根據當次資料 highlight 排名第一的結果。

Same Analysis + Different Data → Different Report

例如：

United States → Gaming leads, 1.3M median views

Germany → Shows leads, 505.2K median views

What Do We Persist?

當一個 Analysis 的邏輯已經被確認之後，我們需要把未來再次執行它所需要的內容保存下來：

• user intent 與 domain knowledge
• confirmed analysis code
• output / report guidance

概念上可以表示成：

Analysis = User Intent + Confirmed Code + Report Guidance

這樣未來再次執行相同的 Analysis 時，就不需要重新定義整個分析流程。

Scaling Up

當 Analysis 可以被保存並再次執行之後，下一個問題就會變成：

如果資料變大，或同時需要執行很多個 Analysis，會碰到什麼問題？

例如：

• execution time
• concurrent Analysis
• database query pressure
• sandbox capacity
• task priority 與 dependency

這時候問題就從：

Agent 能不能完成這個 Analysis？

變成：

系統要怎麼有效率、穩定地執行大量 Analysis？

之後會稍微談論到 system design 相關的主題，例如 concurrency、sandbox capacity，以及 execution optimization。